<?php

namespace Kunfeng\Dify\Client;

use Kunfeng\Dify\Callback\ChatStreamCallback;
use Kunfeng\Dify\Exception\DifyApiException;
use Kunfeng\Dify\Model\Chat\ChatMessage;
use Kunfeng\Dify\Model\Chat\ChatMessageResponse;
use Kunfeng\Dify\Model\Chat\AppInfoResponse;
use Kunfeng\Dify\Model\Chat\AppParametersResponse;
use Kunfeng\Dify\Model\Chat\AppWebAppSettingResponse;
use Kunfeng\Dify\Model\Chat\AppMetaResponse;
use Kunfeng\Dify\Model\Chat\MessageListResponse;
use Kunfeng\Dify\Model\Chat\ConversationListResponse;
use Kunfeng\Dify\Model\Chat\Conversation;
use Kunfeng\Dify\Model\Chat\SuggestedQuestionsResponse;
use Kunfeng\Dify\Model\Chat\AudioToTextResponse;
use Kunfeng\Dify\Model\Chat\AnnotationListResponse;
use Kunfeng\Dify\Model\Chat\Annotation;
use Kunfeng\Dify\Model\Chat\AnnotationReply;
use Kunfeng\Dify\Model\Chat\VariableResponse;
use Kunfeng\Dify\Model\Common\SimpleResponse;

/**
 * Dify 对话型应用客户端接口
 */
interface DifyChatClientInterface extends DifyBaseClientInterface
{
    /**
     * 发送对话消息（阻塞模式）
     */
    public function sendChatMessage(ChatMessage $message): ChatMessageResponse;

    /**
     * 发送对话消息（流式模式）
     */
    public function sendChatMessageStream(ChatMessage $message, ChatStreamCallback $callback): void;

    /**
     * 停止对话消息
     */
    public function stopChatMessage(string $taskId, string $user): SimpleResponse;

    /**
     * 消息反馈（点赞）
     */
    public function feedbackMessage(string $messageId, string $rating, string $user, ?string $content = null): SimpleResponse;

    /**
     * 获取下一轮建议问题列表
     */
    public function getSuggestedQuestions(string $messageId, string $user): SuggestedQuestionsResponse;

    /**
     * 获取会话历史消息
     */
    public function getMessages(string $conversationId, string $user, ?string $firstId = null, ?int $limit = null): MessageListResponse;

    /**
     * 获取会话列表
     */
    public function getConversations(string $user, ?string $lastId = null, ?int $limit = null, ?string $sortBy = null): ConversationListResponse;

    /**
     * 删除会话
     */
    public function deleteConversation(string $conversationId, string $user): SimpleResponse;

    /**
     * 会话重命名
     */
    public function renameConversation(string $conversationId, string $name, bool $autoGenerate, string $user): Conversation;

    /**
     * 语音转文字
     */
    public function audioToText(string $filePath, string $user): AudioToTextResponse;

    /**
     * 语音转文字（流）
     */
    public function audioToTextStream($inputStream, string $fileName, string $user): AudioToTextResponse;

    /**
     * 文字转语音
     */
    public function textToAudio(?string $messageId, ?string $text, string $user): string;

    /**
     * 获取应用元数据
     */
    public function getAppMeta(): AppMetaResponse;

    /**
     * 获取标注列表
     */
    public function getAnnotations(?int $page = null, ?int $limit = null): AnnotationListResponse;

    /**
     * 创建标注
     */
    public function saveAnnotation(string $question, string $answer): Annotation;

    /**
     * 更新标注
     */
    public function updateAnnotation(string $annotationId, string $question, string $answer): Annotation;

    /**
     * 删除标注
     */
    public function deleteAnnotation(string $annotationId): SimpleResponse;

    /**
     * 标注回复初始设置
     */
    public function annotationReply(string $action, string $embeddingProviderName, string $embeddingModelName, int $scoreThreshold): AnnotationReply;

    /**
     * 查询标注回复初始设置任务状态
     */
    public function getAnnotationReply(string $action, string $jobId): AnnotationReply;

    /**
     * 获取对话变量
     */
    public function getConversationVariables(string $conversationId, string $user, ?string $lastId = null, ?int $limit = null, ?string $variableName = null): VariableResponse;
}
